jsdoc-api

What is jsdoc-api?

The jsdoc-api npm package provides a programmatic interface to JSDoc, allowing you to generate documentation from JavaScript source code comments. It can be used to parse JSDoc comments and generate JSON output, making it easier to integrate JSDoc functionality into build processes or other tools.

What are jsdoc-api's main functionalities?

Generate Documentation

This feature allows you to generate documentation from JavaScript files. The `renderSync` method processes the specified files and generates the documentation.

const jsdoc = require('jsdoc-api');

jsdoc.renderSync({
  files: 'path/to/your/file.js'
});

Parse JSDoc Comments

This feature allows you to parse JSDoc comments from a source string. The `explainSync` method returns a JSON representation of the parsed comments.

const jsdoc = require('jsdoc-api');

const docs = jsdoc.explainSync({
  source: '/**
   * A description of the function.
   * @param {string} name - The name of the person.
   * @returns {string} A greeting message.
   */
  function greet(name) {
    return `Hello, ${name}!`;
  }'
});

console.log(docs);

Configure JSDoc Options

This feature allows you to use a configuration file to customize the JSDoc generation process. The `configure` option specifies the path to a JSDoc configuration file.

const jsdoc = require('jsdoc-api');

const docs = jsdoc.explainSync({
  files: 'path/to/your/file.js',
  configure: 'path/to/jsdoc.conf.json'
});

console.log(docs);

Other packages similar to jsdoc-api

documentation

The `documentation` package is another tool for generating documentation from JavaScript comments. It offers a command-line interface and programmatic API, similar to jsdoc-api. It supports ES6+ syntax and can output documentation in various formats, including HTML and Markdown.

esdoc

The `esdoc` package is designed specifically for ES6+ JavaScript. It provides a comprehensive documentation generation tool with support for various plugins and themes. Compared to jsdoc-api, esdoc offers more modern syntax support and additional customization options.

typedoc

The `typedoc` package is a documentation generator for TypeScript projects. It generates documentation based on TypeScript type annotations and comments. While jsdoc-api focuses on JavaScript, typedoc is tailored for TypeScript, providing better integration with TypeScript's type system.

README

jsdoc-api

A programmatic interface for jsdoc3 with a few features:

• Sync and async (Promise) interfaces on the two main jsdoc operations ('explain' and 'render documentation').
• Input (source code) can supplied as a string or set of file names/globs.
• Optional caching, dramatically speeding up future invocations with the same input.

Synopsis

> const jsdoc = require('jsdoc-api')

> jsdoc.explainSync({ source: '/** example doclet */ \n var example = true' })
[ { comment: '/** example doclet *∕',
   meta:
    { range: [ 28, 42 ],
      filename: 'nkrf18zlymohia4i29a0zkyt84obt9.js',
      lineno: 2,
      path: '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T',
      code:
       { id: 'astnode100000002',
         name: 'example',
         type: 'Literal',
         value: true } },
   description: 'example doclet',
   name: 'example',
   longname: 'example',
   kind: 'member',
   scope: 'global' },
 { kind: 'package',
   longname: 'package:undefined',
   files: [ '/var/folders/74/tqh7thm11tq72d7sjty9qvdh0000gn/T/nkrf18zlymohia4i29a0zkyt84obt9.js' ] } ]

API Reference

• jsdoc-api
  • static
    • .cache : cache-point
    • .explainSync([options]) ⇒ Array.<object>
    • .explain([options]) ⇒ Promise
    • .renderSync([options])
  • inner
    • ~JsdocOptions
      • .files : string | Array.<string>
      • .source : string
      • .cache : boolean
      • .access : string
      • .configure : string
      • .destination : string
      • .encoding : string
      • .private : boolean
      • .package : string
      • .pedantic : boolean
      • .query : string
      • .recurse : boolean
      • .readme : string
      • .template : string
      • .tutorials : string

jsdoc.cache : cache-point

The cache-point instance used when cache: true is specified on .explain() or .explainSync().

Kind: static property of jsdoc-api

jsdoc.explainSync([options]) ⇒ Array.<object>

Returns jsdoc explain output.

Kind: static method of jsdoc-api
Prerequisite: Requires node v0.12 or above

Param	Type
[options]	JsdocOptions

jsdoc.explain([options]) ⇒ Promise

Returns a promise for the jsdoc explain output.

Kind: static method of jsdoc-api
Fulfil: object[] - jsdoc explain output

Param	Type
[options]	JsdocOptions

jsdoc.renderSync([options])

Render jsdoc documentation.

Kind: static method of jsdoc-api
Prerequisite: Requires node v0.12 or above

Param	Type
[options]	JsdocOptions

Example

jsdoc.renderSync({ files: 'lib/*', destination: 'api-docs' })

jsdoc-api~JsdocOptions

The jsdoc options, common for all operations.

Kind: inner class of jsdoc-api

• ~JsdocOptions
  • .files : string | Array.<string>
  • .source : string
  • .cache : boolean
  • .access : string
  • .configure : string
  • .destination : string
  • .encoding : string
  • .private : boolean
  • .package : string
  • .pedantic : boolean
  • .query : string
  • .recurse : boolean
  • .readme : string
  • .template : string
  • .tutorials : string

options.files : string | Array.<string>

One or more filenames to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.source : string

A string containing source code to process. Either this or files must be supplied.

Kind: instance property of JsdocOptions

options.cache : boolean

Set to true to cache the output - future invocations with the same input will return immediately.

Kind: instance property of JsdocOptions

options.access : string

Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private".

Kind: instance property of JsdocOptions

options.configure : string

The path to the configuration file. Default: path/to/jsdoc/conf.json.

Kind: instance property of JsdocOptions

options.destination : string

The path to the output folder. Use "console" to dump data to the console. Default: ./out/.

Kind: instance property of JsdocOptions

options.encoding : string

Assume this encoding when reading all source files. Default: utf8.

Kind: instance property of JsdocOptions

options.private : boolean

Display symbols marked with the @private tag. Equivalent to "--access all". Default: false.

Kind: instance property of JsdocOptions

options.package : string

The path to the project's package file. Default: path/to/sourcefiles/package.json

Kind: instance property of JsdocOptions

options.pedantic : boolean

Treat errors as fatal errors, and treat warnings as errors. Default: false.

Kind: instance property of JsdocOptions

options.query : string

A query string to parse and store in jsdoc.env.opts.query. Example: foo=bar&baz=true.

Kind: instance property of JsdocOptions

options.recurse : boolean

Recurse into subdirectories when scanning for source files and tutorials.

Kind: instance property of JsdocOptions

options.readme : string

The path to the project's README file. Default: path/to/sourcefiles/README.md.

Kind: instance property of JsdocOptions

options.template : string

The path to the template to use. Default: path/to/jsdoc/templates/default.

Kind: instance property of JsdocOptions

options.tutorials : string

Directory in which JSDoc should search for tutorials.

Kind: instance property of JsdocOptions

---

© 2015-24 Lloyd Brookes <[e-mail]>.

Tested by test-runner. Documented by jsdoc-to-markdown.